溪夜的音频博客HomeAbout MeArchivesTags
人人都能用 WAAPI（四）Beyond WAAPI
字数总计: 2.3k|阅读时长: 8 分钟

大家好，我是溪夜。
在《人人都能用 WAAPI》第四篇的文章中，会分享一个我个人开发的，提高 WAAPI 使用效率的程序。作为一名技术音频设计师，我的逻辑是只要一件事并非偶发且重复两次以上，那么使用代码将其优化就有意义。
与此同时，还有另一个 WAAPI 项目及本系列文章的一些补遗。
文章中的两个项目分别是：

  • 项目一：我个人开发的 WAAPI Code Generator，它的功能对应系列文章的主题《人人都能用 WAAPI》。这是一个编写 WAAPI 代码的“元工具”，通过提供一种更优雅且一站式的使用方法，进一步提高了 WAAPI 编码效率。
  • 项目二：我与腾旭光子工作室的技术音频设计师李 AA 共同开发的 WAAPI Database，这个项目是中通过合理的 API 运用，实现了抓取 Wwise 内的所需信息，并通过轻量数据库 SQLite 对数据进行储存管理。

为了让初学者更好理解，除了对项目的整个架构进行分析，我会尽量对其中涉及到 WAAPI 的代码进行注释，以方便大家参考。
最后，作为对文档中薄弱部分的补充，本文末尾还会附上在游戏引擎中如何调用 WAAPI 的讲解。

本文目录：

[toc]

WAAPI 的“元工具”：WAAPI Code Generator

1.1. 对现有工作流的思考

在使用 WAAPI 时很容易遇到这样的痛点：

  1. 面对 ak.wwise.core.object.get 或 ak.wwise.core.object.create 这种选项繁杂的 API，手写 JSON 格式的配置代码块着实体验不佳，一不小心写错了符号还需修改。
  2. 无论是否遵循本文曾提到的分类逻辑，在文档中搜寻想要的 API 时都得在那些长长的 API 名中费劲挖掘一番。

本着提高技术音频设计师效率的逻辑，我在思考能否进行一类元工具的开发。就像对待重复代码块写作时会用到 Code Snippets 一样，尽量减少重复工作带来的时间浪费。
这也是 WAAPI Code Generator 诞生的动机，我的初衷就是希望把 WAAPI 的使用变的更加简单且工具化。

1.2. 设计原理

我们以 ak.wwise.core.object.get 为例，在 Python 中调用这个 API 需要：

  1. 根据文档选定需要使用的参数，form 决定从何处获取，transform 决定变换条件，此外还有可选参数 Options 决定返回值和平台。
  2. 为 form 手动获取 GUID 或路径，其他的参数要按需从文档中获取正确的参数。
  3. 书写 JSON 配置的语法结构，把对应的参数放到正确的地方。
  4. 测试代码。（如果 JSON 格式不小心写错，Debug 时间到！）

而在 WAAPI Code Generator 中你只需要：

  1. 在左边第一栏中间选择需要的 WAAPI class，选中 ak.wwise.core 即可轻松在下面找到 ak.wwise.core.object.get。
  2. 在程序中间第二栏的下拉列表里选择所需的参数。此时右边会有官方文档及我所书写的文档注释。如果需要使用 GUID 或工程路径等信息作为参数，直接在左边下方的工程浏览器里可清晰看到当前工程的完整目录架构，随时获取所需信息并添加到配置参数中。
  3. 选中所需的语言，即会按照该语言所需的参数格式生成代码。点击 Generate，代码默认会自动复制到剪贴板，随后粘贴至你的代码编辑器内即可。

容易看出，我优化掉了 WAAPI 中繁琐的步骤，例如反复的翻阅文档、精心书写 JSON 格式、去 Wwise 内拷贝 GUID 等。

1.3. 使用方法

todo：添加图片、详细介绍
GitHub 地址：https://github.com/zcyh147/WAAPI-Code-Generator

  1. 打开 GitHub 仓库，在 releases 中下载对应系统的最新版，解压到你喜欢的目录中
  2. 根据 Wwise 内的 WAAPI 设置，填入服务器和端口号来连接 WAAPI 服务器。默认情况下不需修改，直接点击 Connect 按钮即可。
  3. 本程序遵循 Don’t Make Me Think 原则，采用“左中右”三分栏的设计，用户从左到右进行顺序操作即可，非常简单。

1.4. 源码分析

因 WAAPI Code Generator 中只用到了 WAAPI 的 API 反射函数，其余部分都是 Python 的自带或第三方库，所以程序的源码在此不做分析。
在 GitHub 仓库中的源码具有完善的英文注释和 Docstrings，大家可以自行参考。

WAAPI 数据抓取器：WAAPI Database

2.1. 功能简述

从项目名 WAAPI Database 中不难看出，程序的主要目的是对 Wwise 中各种信息进行抓取，其核心功能通过 ak.wwise.core.object.get 来实现。
抓取后的数据会使用 SQLite 保存在本地数据库之中，这是一款轻量且免配置的数据库工具。如果读者不熟悉数据库也没关系，可把数据库当做是一种结构更复杂但更易于管理的电子表格结构，暂不予深究。
WAAPI Database 的运行方式是借助 Wwise 在 SoundBank 生成时执行的 PostXXXX 行为，通过这个功能在生成 SoundBank 后执行一个 Command Line Tools 文件，从而触发 WAAPI Database 中的功能代码。
在我的 GUI 版工具中，还有手动抓取的功能，即无需等 SoundBank 生成也可直接抓取当前工程的数据，作为 WAAPI Database 的功能补充。
GitHub 地址：https://github.com/jazzlost/WaapiDatabase

2.2. 代码架构分析

下面通过思维导图把项目中涉及到的所有文件列出其逻辑关系，以直白的展示程序的架构。
以下代码解析基于 WAAPI Database V0.3，WAAPI 版本2019.2。

2.3. WAAPI 代码源码分析

代码文件中关于 wd_sqlite_interface.py 和 wd_sqlite_utils.py 的部分为 SQLite 相关的内容，在此不做讲解。

wd_client.py

wd_config.py

wd_parser.py

wd_processor.py

wd_args.py

waapi_config.json

waapi_database.wcmdline

wd_gui.py

2.4. UI 设计

原型设计

代码实现

工作效果

在游戏引擎中调用 WAAPI

3.1. Unity

3.1.1. 配置与连接测试

想要正常使用 Unity Integration 中的 WAAPI 功能，首先请确保你的 Wwise 版本大于等于 2018.1，并完成与 Unity 的整合。
为了测试方便，建议创建一个全新的工程以方便测试运行脚本。
在 Project 选项卡中创建一个新的 C# 脚本命名为 waapi，并修改代码为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
using System.Collections.Generic;
using System.Collections;
using UnityEngine;

public class waapi : MonoBehaviour
{
    void Start()
    {
        // 这里改为 WAMP 服务器的地址和端口，没修改过的话用默认值即可
        if (AkWaapiClient.Connect("127.0.0.1", 8080))
        {
            Debug.Log("Connected to WAMP server");
        }
        else
        {
            Debug.Log("Connect fail!");
        }
    }
}

将其拖拽到 Main Camera 上并运行游戏，如果连接顺利，会在控制台看到以下信息：

1
2
Connected to WAMP server
UnityEngine.Debug:Log(Object)

3.1.2 JSON 字符串和 C# 字符串的互转

因为 WAAPI 的远程调用需要以 JSON 格式传递参数，可以通过文档中提供的WaapiJsonClassBase 类，进行 JSON 与字符串的互相转换：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public class WaapiJsonClassBase<T>
{
    # 重写 ToString() 方法，把返回值改为用 JsonUtility 的 ToJson 方法转换传入的 C# 字符串返回为 JSON 字符串
    public override string ToString()
    {
        return JsonUtility.ToJson(this);
    }
    
    # 隐式转换
    public static implicit operator string(WaapiJsonClassBase<T> obj)
    {
        return obj.ToString();
    }
    
    # 使用 JsonUtility 的 FromJson 方法把 JSON 字符串转为 C# 字符串
    public static T Create(string FromJson)
    {
        return JsonUtility.FromJson<T>(FromJson);
    }
}

3.1.2. Functions 类 API 使用

参考：https://www.audiokinetic.com/zh/library/edge/?source=Unity&id=unity_waapi.html

3.1.3. Topics 类 API 使用

3.2. Unreal Engine

3.2.1 配置

Unreal Integration 默认会自动连接到当前整合的 Wwise 工程中，为了验证这一点，可打开 Project Settings - Integration Settings，查看窗口中的 Auto Connect to WAAPI 是否为勾选状态。
在 Wwise - User Settings 中，可以配置用来连接到 WAAPI 服务器的 IP 地址和端口。
因为 FAkWaapiClient 需要使用 AkAudio 作为依赖，可以参考文档中的这部分：https://www.audiokinetic.com/library/edge/?source=SDK&id=waa_cpp_sample.html

3.2.2. Functions 类 API 使用

3.2.3. Topics 类 API 使用

3.3. Godot

结语

感谢在我人生中压力最大的时光中给予我鼓励和帮助的朋友们和家人，以及我挚爱的所有音乐家的作品们，没有你们，我是无法完成这篇体量庞大的文章的。
之后如果我和朋友们还有优质的 WAAPI 开源项目，仍然会汇总后以文章的形式发布。
与此同时，建议大家看看现有的 WAAPI 项目实际应用，如：

  1. Wwise Authoring API（WAAPI）的三个开源工程：https://blog.audiokinetic.com/waapi-three-open-source-projects-for-wwise-authoring-api/
  2. 连通 Wwise 和 REAPER – 第 1 部分：WAAPI Transfer：https://blog.audiokinetic.com/connecting-wwise-and-reaper-part-1-waapi-transfer/
  3. WAAPI AK-thon：https://blog.audiokinetic.com/ak-thon-waapi/
  4. WAAPI Formula：https://github.com/jazzlost/Waapi_Formula
文章作者: 溪夜
文章链接: http://xiye.art/2021/01/15/WAAPI 一文通（五）/
版权声明: 本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 溪夜的音频博客！
音频编程